====== ABC 2.0 Plugin (for displaying sheet music) ======
---- plugin ----
description: Displays sheet music (input ABC, output SVG and MIDI)
author : Anika Henke
email : anika@selfthinker.org
type : syntax, action
lastupdate : 2024-01-21
compatible : 2020-07-29 "Hogfather", 2023-04-04
depends :
conflicts : abc
similar : abc
tags : music, markup_language, media, export
downloadurl: https://github.com/selfthinker/dokuwiki_plugin_abc2/archive/master.zip
bugtracker : https://github.com/selfthinker/dokuwiki_plugin_abc2/issues
sourcerepo : https://github.com/selfthinker/dokuwiki_plugin_abc2/
donationurl: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=11071728
screenshot_img : :plugin:abc2-plugin.png
----
This plugin lets you add [[http://abcnotation.com/|ABC syntax]] (a musical notation language) to a wiki page and turns that into SVG images of sheet music and MIDI sounds.
It uses [[https://www.abcjs.net/|abcjs]], [[https://chiselapp.com/user/moinejf/repository/abc2svg|abc2svg]] and [[http://dev.music.free.fr/web-demo/$ABC_UI.html|$ABC_UI]] for that. It is the successor of the [[plugin:abc|ABC Plugin]].
===== Installation =====
Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually.
==== Configuration and Settings ====
* ''library'': choose one of the different ABC libraries (they all have their [[#Comparison between different libraries|pros and cons]])
* ''abcok'': activate the library (deactivating is good for debugging)
* ''showSource'': show the original source (doesn't work with abc2svg)
* ''stayLibre'': only use Open Source components (abc2svg uses an external soundfont which is not Open Source, setting this will deactivate the sound for abc2svg so it won't be used)
* ''abcuiConfig'': configuration parameters for abc-ui (space separated numbers, first number is score width in cm, second number is zoom level)
==== Potential Template Changes ====
Two of the libraries (abc2svg and $ABC_UI) produce images which are not responsive. That means that when viewed on a mobile device or when zoomed in, they will break out of the page. That will look broken but is at least readable and won't cut off.
That only works when the template's styling allows that. There is a fix for the default 'dokuwiki' template in this plugin. But if you're using a different template, that fix might not work.
You might need to override something that hides part of the image, e.g. changing ''overflow: hidden'' somewhere to ''overflow: visible'' via a [[devel:css#user_styles|user style]].
The images also break out of the page in desktop view with a sidebar in the default template.
That can be mitigated with the tempalate's ''%%__site_width__%%'' style.ini setting, or the ''abcuiConfig'' setting specifically for the $ABC_UI library.
===== Usage and Syntax =====
X:42
T:Test
M:4/4
K:C
"C" C2 D2 E2 G2 |"C" c8 |]
w:This is just a test
This code will produce an SVG file which shows the sheet music and a MIDI file which you can play.
This is a screenshot of the output of all three libraries:
{{:plugin:abc2-plugin.png?nolink|}}
==== Transposition ====
You can transpose any ABC by adding extra parameters (separated by spaces, 8 different values allowed). These parameters have to be numbers between -12 and 12, which is the amount of semitones that the tune will be transposed up (if positive) or down (if negative).
X:42
T:Test
M:4/4
K:C
"C" C2 D2 E2 G2 |"C" c8 |]
w:This is just a test
This will show the tune in the original key, as well as automatically transposed up to G major and down to A major.
Please note: Transposition does not work with abcjs.
===== Comparison between different libraries =====
You can choose between different ABC libraries. They all have their pros and cons.
| ^ abcjs ^ abc2svg ^ $ABC_UI ^
^ license | MIT | GPL2 or later (but it uses a resource which is not Open Source and can be switched off in the config) | GPL2 or later (uses abc2svg) |
^ responsiveness | the score gets smaller on mobile but that also means it's more difficult to read | the score doesn't get smaller and breaks out of the page on mobile but that also means it's easier to read | the score doesn't get smaller and breaks out of the page on mobile but that also means it's easier to read |
^ only works within plugin syntax | ❌ no, the script grabs anything that looks like ABC and converts it | ❌ no, the script grabs anything that looks like ABC and converts it | ✅ yes |
^ can show original source | ✅ yes | ❌ no ((that means the 'showSource' config has no effect)) | ✅ yes |
^ works in edit preview | ✅ yes | ❌ no | ✅ yes |
^ can transpose | ❌ no ((abcjs has the ability to transponse, but not through the way it is implemented in this plugin)) | ✅ yes | ✅ yes |
^ notes follow sound | ❌ no ((abcjs has the ability for this, but not in this version of the library)) | ✅ yes | ✅ yes |
^ sound includes chords | ✅ yes | ❌ no | ❌ no |
^ extra features | ❌ no | ✅ yes, lots of extra [[http://moinejf.free.fr/abcm2ps-doc/index.html|parameters]] and some differing [[http://moinejf.free.fr/abcm2ps-doc/features.xhtml|features]] | ✅ yes, same as abc2svg, plus can switch voices in the sound on and off and can switch between different tempos (via ''%%tempo'') |
^ how the sound starts | player underneath, play/pause | plays from start when clicking on sheet, or plays from specific point when clicking on single notes | player button on the top, play/stop |
^ pitfalls | | if ABC is used outside of the ''%%%%'' syntax, needs no space after "X:" or it won't render ((this is fixed and will be in a future version)) | better to use Q (or else the sound is super slow) |
^ bugs or missing features | gets some broken rhythm wrong ((this was fixed upstream and will be fixed in a future release)), missing support for octave modifier | breaks some of DokuWiki's JavaScript (TOC toggle) | loading soundfont before playing any sound means it takes about 2 seconds longer to load than the other libraries, no repo makes it unclear when and how the code gets updated, missing some glyphs for decorations (e.g. ''!slide!'') |
^ accessibility issues | | cannot play sound with keyboard only | no accessible names for interactive elements (player button, checkboxes and tempo dots), uses layout tables |
===== Differences to old ABC Plugin =====
The predecessor of this plugin is the [[plugin:abc|ABC Plugin]]. It still works but cannot be used alongside the ABC2 Plugin because they both use the same syntax.
Here are the differences between the two plugins and the reason why there is a new plugin...
The ABC2 Plugin is much easier to install than the old ABC Plugin. You don't have to build and install different backend programmes outside of the wiki anymore. Everything you need is now included in the plugin and is run with JavaScript.
The old ABC Plugin gave admins the choice between different output types: image, image and sound, or image, sound and PDF, and those could be downloaded. The successor now has less choices, it only creates image and sound, no PDFs and no downloads.
But the image quality of the new plugin is much better. It produces SVGs which are always much clearer and sharper than PNGs which don't scale well and can look grainy on retina devices. SVGs also look much better when printed and scores can easily be printed via the browser's print functionality.
===== Version history =====
{{rss>https://github.com/selfthinker/dokuwiki_plugin_abc2/commits/master.atom date}}
===== Discussion =====
//Add questions here...//
*got no github accound, so: after the latest DokuWiki update (rc2022-06-26 "Igor" RC2) the SVG output is tiny, next to invisible... Maybe any ideas, how to fix it? Great Plugin, btw. //2022-07-08 14:12//
* This has been fixed now (in version 2024-01-20).
* Congratulations! This is a huge update. Thanks for your dedication and consistent commitment for this difficult task //(and I know the level of dificulty)//. I am not sure you done this for the sake of music or for DokuWiki :-); but anyhow, nice and serious job. --- [[user>florious|Florin]] //2021-02-22 14:12//
* Awesome plugin. The default grand piano voice (MIDI program number one) becomes marimba above high 'F' on the great stave [[user>Auvergine|Austvergine]] //2022-10-24 11:50//
* Am I the only one who has trouble with uploading media files with ABC2 active? (the Media Manager still works fine) wun //2022-12-27 12:50//